home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 18 / CU Amiga Magazine's Super CD-ROM 18 (1997)(EMAP Images)(GB)[!][issue 1998-01].iso / CUCD / Online / hsc / docs-source / options.hsc < prev    next >
Encoding:
Text File  |  1997-06-04  |  12.2 KB  |  294 lines
  1. <WEBPAGE chapter="hsc - " title="Invoking Hsc"
  2.     PREV="install.html"
  3.     NEXT="examples.html"
  4.     QTEXT=("shoulder, bicep, elbow, arm<BR>"
  5.           +"forearm, thumb, wrist, knuckle, palm<BR>"
  6.           +"middle, pinky, index, ring<BR>"
  7.           +"dinner bell dinner bell ding")
  8.     QAUTHOR='They Might Be Giants, "Dinner Bell"'>
  9.  
  10. <*
  11. ** macro to format an explanation
  12. *>
  13. <$MACRO explan TITLE:string/r NAME:string ONLYDEFTAG:bool>
  14. <** create named reference **>
  15. <DT>
  16. <$stripws>
  17. <$IF COND=(SET NAME)>
  18.     <A NAME=(Name)>
  19. <$ELSE>
  20.     <A NAME=(Title)>
  21. </$IF>
  22. <$stripws>
  23. <KBD><(title)></KBD></A>
  24. <$IF COND=(ONLYDEFTAG)>
  25. (for use within <ln_deftag> only)
  26. </$IF>
  27. <DD>
  28. </$MACRO>
  29.  
  30.  
  31. This section covers which
  32. <A HREF="#options">options</A> and
  33. <A HREF="#switches">switches</A> you can pass to <hsc>, 
  34. and which <A HREF="#exitcodes">exit codes</A> are returned to CLI.
  35.  
  36. <H2><A NAME="general.rules">General Rules For Options</A></H2>
  37.  
  38. <P>As <hsc> is an tool developed under AmigaOS and I never liked
  39. the cryptic "<KBD>cmd -cvf -osepp.x</KBD>"-way of invoking commands coming
  40. from Unix, <hsc> uses a syntax like most commands of AmigaOS;
  41. even for ports on other operating-systems. (<TechNote> AmigaOS provides
  42. an OS-function called <CODE>ReadArgs()</CODE> for 
  43. argument-parsing.)</P>
  44.  
  45. <P>All options and switches are case-insensitive. If you start <hsc>
  46. without any options, a short help message will be displayed.</P>
  47.  
  48. <P>Options can be followed by modifiers, which specify things such as
  49. the type of the option.  Modifiers are specified by following the
  50. option with a '/' and a single character modifier.  Multiple modifiers
  51. can be specified by using multiple '/'s.  Valid modifiers are:</P>
  52.  
  53. <DL>
  54. <DT><KBD>/S</KBD> - Switch.  
  55. <DD>This is considered a boolean variable, and will be
  56.    set if the option name appears in the command-line.  
  57. <DT><KBD>/K</KBD> - Keyword.  
  58. <DD>This means that the option will not be filled unless
  59.     the keyword appears.  For example if the template is 
  60.     <qq><KBD>Name/K</KBD></qq>,
  61.     then unless <qq><KBD>Name={string}</KBD></qq> 
  62.     or <qq><KBD>Name {string}</KBD></qq> appears in the
  63.     command line, Name will not be filled.
  64.  
  65. <DT><KBD>/N</KBD> - Number.  
  66. <DD>This parameter is considered a decimal number.
  67.     If an invalid number is specified, an error will be returned.  
  68. <*
  69.         /T - Toggle.  This is similar to a switch, but when specified causes
  70.              the boolean value to "toggle".  Similar to /S.*>
  71. <DT><KBD>/A</KBD> - Required.
  72. <DD>This keyword must be given a value during command-line
  73.     processing, or an error is returned.
  74. <*
  75.         /F - Rest of line.  If this is specified, the entire rest of the line
  76.              is taken as the parameter for the option, even if other option
  77.              keywords appear in it.*>
  78. <DT><KBD>/M</KBD> - Multiple strings.
  79. <DD>This means the argument will take any number strings.
  80.     Any arguments not considered to be part of another option will be 
  81.     added to this option.  
  82. </DL>
  83.  
  84. <H2><A NAME="options">Options</A></H2>
  85.  
  86. <DL>
  87. <EXPLAN TITLE="FROM/M" NAME="from">
  88.     Specifies the input filename. To use <stdin> as
  89.     input file, the pseudo filename <CODE>STDIN</CODE> (case sensitive)
  90.     should be specified. If you specify more than one file,
  91.     the last file is taken as main source, and all previous files are
  92.     included before it. This is useful to include macro-definitions
  93.     within the command-line instead of an <ln_include> in the hsc-source.
  94. <EXPLAN TITLE="TO/K" NAME="to">
  95.     Specifies the output filename or the destination directory.
  96.     If the argument ends with a "<KBD>/</KBD>" (or also "<KBD>:</KBD>"),
  97.     it is interpreted as a directory. In this case, the name of the
  98.     output file is created from the name of the input file, with an
  99.     extension specified (see below). If no output file is set, <stdout> 
  100.     is used instead.<BR>
  101.     For details, read the section about
  102.     <A HREF="fileargs.html">File Options</A>
  103.     
  104. <EXPLAN TITLE="EXTENSION/K" NAME="extension">
  105.     If you specify a directory for output, the output-filename
  106.     will depend on the input-filename and the extension specified
  107.     with this options. If you do not set an extension, "<CODE>html</CODE>"
  108.     will be used. A <period> will be added automatically.
  109.     Setting <KBD>EXTENSION=.</KBD> will omit this and result into exactly
  110.     the same filename as the input.
  111.     If you specify a complete filename for output, this option has no
  112.     effect.
  113. <EXPLAN TITLE="MSGFILE/K" NAME="msgfile">
  114.     Redirects messages to a file. By default, <stderr> ist used.
  115. <EXPLAN TITLE="MSGFORMAT/K" NAME="msgformat">
  116.     Describes how messages should be displayed. Conversion specifications:
  117.     <PRE>
  118.         %f      filename
  119.         %x, %y  location in file (column, line)
  120.         %c      message class
  121.         %i      message id (numeric)
  122.         %m      message text
  123.         %n      inserts a linefeed
  124.     </PRE>
  125.     Example: To get GCC-like messages, use
  126.     <CODE>MSGFORMAT="%f:%y: %c %i: %m"</CODE>.
  127. <EXPLAN TITLE="PREFSFILE/K" NAME="prefsfile">
  128.     Specifies filename for <A HREF=":features/prefs.html">sytax-definition</A>
  129.     to be used, if you don't want to use the defaults.
  130.  
  131. <EXPLAN TITLE="PRJFILE/K" NAME="prjfile">
  132.     Stores some information about the document currently processing
  133.     in a seperate file to extend functionality. Read the section
  134.     about <A HREF="project/index.html">Project management</A> for more
  135.     details. Note that all documents within a project should use the
  136.     same project-file.
  137.  
  138. <EXPLAN TITLE="DEFINE=DEF/K/M" NAME="define">
  139.     Defines a global attribute. The syntax is equal to <ln_define>, exept
  140.     that you need no quotes surrounding the value.<BR>
  141.     Example: <CODE>DEFINE "hugo:string=hugo was here"</CODE>
  142.  
  143. <EXPLAN TITLE="IGNORE=IGN/K/M" NAME="ignore">
  144.  
  145.     <*
  146.      * TODO: describe "ignore PORT, STYLE, JERK"
  147.      *>
  148.     Ignore warning message number. Usually, <KBD>IGNORE</KBD> needs a numeric
  149.     argument and can occur multiple. Example:<BR>
  150.     <BLOCKQUOTE>
  151.         <KBD>IGNORE=21 IGN=18 IGN 3</KBD>         (ignore warnings #21, #18, #3)
  152.     </BLOCKQUOTE>
  153.     Additionally, you can specify some special values, which will ignore
  154.     whole groupss of messages:
  155.     <UL>
  156.     <LI><KBD>ALL</KBD>
  157.         Ignore all non-error messages
  158.     <LI><KBD>NOTES</KBD>
  159.         Ignore all notes
  160.     <LI><KBD>BADSTYLE</KBD>
  161.         Ignore all bad style warnings
  162.     </UL>
  163.     These values add new messages to the list of messages
  164.     to be ignored, but do not reset any <KBD>IGNORE</KBD>s passed before.
  165.  
  166. <EXPLAN TITLE="MODE/K" NAME="mode">
  167.     Set base mode for syntax check. Legal values are <KBD>PEDANTIC,
  168.     NORMAL</KBD> and <KBD>RELAXED</KBD>. Default is <KBD>NORMAL</KBD>.
  169.     This only disables several messages and warnings from the beginning.
  170.     Any <KBD>IGNORE</KBD>s passed before are reseted.
  171.  
  172. <EXPLAN TITLE="QUOTESTYLE/K" NAME="quotestyle">
  173.     Specifies which kind of quotes should be used to surround 
  174.     attribute-values. <KBD>KEEP</KBD> keeps the user-kind, 
  175.     <KBD>DOUBLE</KBD> tries to assign double quotes 
  176.     (eg. <CODE>"value"</CODE>), 
  177.     <KBD>SINGLE</KBD> tries to assign single quotes 
  178.     (eg. <CODE>'value'</CODE>) and <KBD>NONE</KBD> will remove
  179.     quotes if possible.
  180.  
  181. <EXPLAN TITLE="INCLUDEDIR=IDIR/K/M" NAME="includedir">
  182.     By default, only the current directory is scanned for files
  183.     to be included (using the CLI option <op_from> or the
  184.     special tags <ln_include> or <ln_exec>). This option adds a
  185.     directory to the list of directories to search for include
  186.     files.
  187.  
  188. <EXPLAN TITLE="STATUS/K" NAME="status">
  189.     Display several status messages (output goes to stderr). Legal
  190.     flags are:
  191.     <UL COMPACT>
  192.     <LI><KBD>QUIET</KBD>: no status messages
  193.     <LI><KBD>LINE</KBD>: display name and line of file currently processing
  194.         Included files are also displayed. After processing a file,
  195.         the filename and the total number of lines remain visible.
  196.     <LI><KBD>VERSION</KBD>: display program title and version
  197.     <LI><KBD>VERBOSE</KBD>: enable verbose status messages; this includes
  198.         the information displayed during the  processing of <ln_exec>
  199.         and some details about images, if <op_getsize> has also been
  200.         enabled.
  201.     <LI><KBD>FULL</KBD>: enable all status messages
  202.     </UL>
  203.     The above flags can be combined by separating them with a <vbar>,
  204.     eg <KBD>STATUS=line|version</KBD>, except for <KBD>QUIET</KBD>
  205.     and <KBD>FULL</KBD>
  206. <EXPLAN TITLE="STRIPTAGS/K" NAME="striptags">
  207.     Strip some specific tags from document. You can specify a list of tags
  208.     which is a string,
  209.     that contains all tags that should be stripped, separated by a
  210.     <vbar>.<BR>
  211.     See also <op_stripcomment> and <op_stripexternal>.
  212. <EXPLAN TITLE="ICONBASE/K" NAME="iconbase">
  213.     Replace all icon entities by images that must be available from
  214.     the base URI specified. If this URI contains an <asterisk>, it 
  215.     will be substituted by the icon name. For
  216.     example, with <KBD>ICONBASE=:icons/*.gif</KBD>, the entity
  217.     <CODE>&back;</CODE>
  218.     is replaced by <TG>IMG SRC=":icons/back.gif" ALT="back"</TG>. Note
  219.     that this argument does not denote a directory, but an URI. It's
  220.     recommended to use a <fe_prjuri>.
  221. <EXPLAN TITLE="SERVERDIR/K" NAME="serverdir">
  222.     With this you can tell <hsc> where it should look for files
  223.     referenced with a server relative URI. The directory has to be
  224.     specified as a <STRONG>native</STRONG> filename of your OS.
  225.     Example:
  226.     <CODE>SERVERDIR=aws:home</CODE> might work fine under AmigaOS,
  227.     <CODE>SERVERDIR=/user/sepp/public_html</CODE> could be used
  228.     on an Unixoid system.
  229. </DL>
  230.  
  231. <H2><A NAME="switches">Switches</A></H2>
  232. <DL>
  233. <EXPLAN TITLE="HELP/S" NAME="help">
  234.     Display a short help message and exit.
  235. <EXPLAN TITLE="LICENSE/S" NAME="license">
  236.     Display a short version of the <A HREF="../COPYING">GNU General
  237.     Public License</A> and exit.
  238. <EXPLAN TITLE="COMPACT/S" NAME="compact">
  239.     <A HREF="features/strip.html">Strip redundant linefeeds
  240.     and white-spaces</A> from output.
  241. <EXPLAN TITLE="-DEBUG/S" NAME="-debug">
  242.     If you've compiled <hsc> in debug-mode, it will send lots of
  243.     information to <stderr>. Otherwise, this option is
  244.     equivalent to <KBD>STATUS=FULL</KBD>.
  245. <EXPLAN TITLE="GETSIZE/S" NAME="getsize">
  246.     <A HREF="features/getsize.html">Get width and height of images</A>
  247.      and set corresponding attributes
  248.     <CODE>WIDTH</CODE> and <CODE>HEIGHT</CODE> with these values;
  249. <EXPLAN TITLE="MSGANSI/S" NAME="msgansi">
  250.     Uses ANSI-sequences to make messages more readable. This option is
  251.     recommended to be used by people who are not smart enough to integrate
  252.     <hsc> in some of the existing project-management environments.
  253. <EXPLAN TITLE="RPLCENT/S" NAME="rplcent">
  254.     <A HREF="features/rplcent.html">Replace special characters</A> with
  255.     their entities (eg <qq><CODE>ü</CODE></qq> becomes 
  256.     <qq><CODE>&uuml</CODE></qq>).
  257. <EXPLAN TITLE="RPLCQUOTE/S" NAME="rplcquote">
  258.     Replace double-quotes (<qq><CODE>"</CODE></qq>) found in the text by 
  259.     <qq><CODE>&quot;</CODE></qq>. This does not affect quotes used inside
  260.     attribute-values.
  261. <EXPLAN TITLE="SMARTENT/S" NAME="smartent">
  262.     Replace special characters <qq><CODE>&</CODE></qq>, 
  263.     <qq><CODE><</CODE></qq>
  264.     and <qq><CODE>></CODE></qq> with their entities
  265.     (<CODE>&amp;, &lt;</CODE> and <CODE>&gt;</CODE>) if they are
  266.     surrounded by white-spaces. 
  267. <EXPLAN TITLE="STRIPBASWS/S" NAME="stripbadws">
  268.     Strip bad white spaces that would have caused <ln_msg id="78">
  269.     or <ln_msg id="79">; this will not strip those which cause
  270.     <ln_msg id="47">. The main advantage of this switch is that
  271.     it allows you to write well structured macros.
  272. <EXPLAN TITLE="STRIPCOMMENT/S" NAME="stripcomment">
  273.     Strip all SGML-comments from input.
  274. <EXPLAN TITLE="STRIPEXTERNAL/S" NAME="stripexternal">
  275.     Strip tags which refer to an external URI.
  276. </DL>
  277.  
  278. <H2><A NAME="exitcodes">Exit Code</A></H2>
  279.  
  280. <P>The exit-code <hsc> returns to the CLI depends on the messages and errors
  281. that have been displayed during runtime.</P>
  282.  
  283. <P>The version for AmigaOS returns 
  284. <UL>
  285. <LI><CODE>0</CODE> on success,
  286. <LI><CODE>5</CODE> if warnings occurred,
  287. <LI><CODE>10</CODE> if errors showed up (also for errors in arguments) and
  288. <LI><CODE>20</CODE> if fatal errors happened (also for out-of-resources).
  289. </UL>
  290.  
  291. For other systems, values like <CODE>0/0/1/2</CODE> are used instead.
  292.  
  293. </WEBPAGE>
  294.